{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/slider';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/slider/package.json';

```jsx import
import {Flex} from '@react-spectrum/layout';
import {Slider} from '@react-spectrum/slider';
```

---
category: Forms
after_version: 3.0.0-alpha.0
---

# Slider

<PageDescription>{docs.exports.Slider.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['Slider']}
  sourceData={[{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/slider/'}]}
  since="3.7.0" />

## Example

```tsx example
<Slider label="Cookies to buy" defaultValue={12} />
```

## Value

Sliders are controlled with the `value` prop and uncontrolled with the `defaultValue` prop. This value must fall between
the Slider's minimum and maximum values, which default to 0 and 100 respectively.

```tsx example
function Example() {
  let [value, setValue] = React.useState(25);
  return (
    <Flex gap="size-150" wrap>
      <Slider
        label="Cookies to buy (Uncontrolled)"
        defaultValue={25} />
      <Slider
        label="Cookies to buy (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}
```

Alternatively, a different scale can be used by setting the `minValue` and `maxValue` props.

```tsx example
<Slider
  label="Cookies to buy"
  minValue={50}
  maxValue={150}
  defaultValue={100} />
```

The slider value can be formatted by using the `formatOptions` prop.
`formatOptions` is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) and is applied based on the current locale.

```tsx example
<Slider
  label="Currency"
  formatOptions={{style: 'currency', currency: 'JPY'}}
  defaultValue={60} />
```

### HTML forms

Slider supports the `name` prop for integration with HTML forms.

```tsx example
<Slider
  label="Opacity"
  defaultValue={50}
  name="opacity" />
```

## Labeling
Value labels are shown above the Slider by default, but they can also be moved to the side or hidden as needed.
The label text should be in sentence case.

```tsx example
<Flex direction="column" maxWidth="size-5000" gap="size-300">
  <Slider label="Cookies to buy" defaultValue={25} />
  <Slider label="Donuts to buy" labelPosition="side" defaultValue={25} />
  <Slider label="Pastries to buy" showValueLabel={false} defaultValue={25} />
</Flex>
```

By default, the value label is formatted as a plain number. This can be customized using the following props.

* `showValueLabel`: Allows you to display or hide the value label.
* `formatOptions`: Allows you to customize the format of the value.
* `getValueLabel`: Allows you to provide a custom function to format the value label.

```tsx example
<Flex direction="column" maxWidth="size-3000" gap="size-300">
  <Slider
    label="Cookies to buy"
    showValueLabel={false}
    defaultValue={90} />
  <Slider
    label="Percent donus eaten"
    maxValue={1}
    step={0.001}
    formatOptions={{style: 'percent', minimumFractionDigits: 1}}
    defaultValue={0.891} />
  <Slider
    label="Donuts to buy"
    maxValue={60}
    getValueLabel={donuts => `${donuts} of 60 Donuts`} />
</Flex>
```

### Accessibility

Depending on the visualization being used (i.e. depending on the `showValueLabel` prop), a `label`, `aria-label`, or `aria-labelledby` prop is required.

### Internationalization

To internationalize a Slider, a localized string should be passed to the `label` prop, `aria-label` prop, or value of the associated `aria-labelledby` element.

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the slider is automatically flipped. In addition,
Slider automatically uses the current locale to format the value label.

## Props

<PropTable component={docs.exports.Slider} links={docs.links} />

## Visual options

### Fill
[View guidelines](https://spectrum.adobe.com/page/slider/#Fill)

```tsx example
<Flex direction="column" gap="size-300">
  <Slider label="Opacity" maxValue={1} formatOptions={{style: 'percent'}} defaultValue={0.9} step={0.01} isFilled />
  <Slider label="Exposure" minValue={-5} maxValue={5} defaultValue={1.83} formatOptions={{signDisplay: 'always'}} step={0.01} fillOffset={0} isFilled />
</Flex>
```

### Gradient
[View guidelines](https://spectrum.adobe.com/page/slider/#Gradient)

```tsx example
<Slider label="Filter density" trackGradient={['white', 'rgba(177,141,32,1)']} defaultValue={.3} maxValue={1} step={0.01} formatOptions={{style: 'percent'}} isFilled  />
```

### Contextual help

A [ContextualHelp](ContextualHelp.html) element may be placed next to the label to provide additional information or help about a Slider.

```tsx example
import {Content, ContextualHelp, Heading} from '@adobe/react-spectrum';

<Slider
  label="Exposure"
  minValue={-100}
  maxValue={100}
  defaultValue={0}
  formatOptions={{signDisplay: 'always'}}
  isFilled
  fillOffset={0}
  contextualHelp={
    <ContextualHelp>
      <Heading>What is exposure?</Heading>
      <Content>Exposure adjusts how bright the image is.</Content>
    </ContextualHelp>
  } />
```

### Disabled
[View guidelines](https://spectrum.adobe.com/page/slider/#Disabled)

```tsx example
<Slider label="Cookies to share" defaultValue={25} isDisabled />
```

## Testing

The Slider features a draggable handle that the user can interact with to change its value.
Please see the following section in the testing docs for more information on how to simulate this action in your
test suite.

[Simulating move event](./testing.html#simulating-move-event)

Please also refer to [React Spectrum's test suite](https://github.com/adobe/react-spectrum/blob/main/packages/%40react-spectrum/color/test/ColorArea.test.tsx) if you find that the above
isn't sufficient when resolving issues in your own test cases.
